/**
 * 
 */
package com.redhat.auditor.webdiff;

import java.util.List;

/**
 * This interface is an abstraction of all of the essential services that a text
 * diff tool needs to provide. It is provided for the benefit of developers
 * wishing to implement their own diff tool.
 * 
 * @since 0.0.0.0
 * @version %I%, %G%
 * @author Trungtin Ton
 * 
 */
public interface Differ {

	/**
	 * Sets the left-side text input. The text on the left should always be the
	 * older, or former, of the two text inputs, i.e. the left should
	 * chronologically precede the right.
	 * <p>
	 * Another term used for the left-hand side of a diff is the "source".
	 * 
	 * @param text
	 *            the text to set as the left-hand side source of the comparison
	 */
	public void setLeftText(String text);

	/**
	 * Sets the right-side text input. The text on the right should always be
	 * the newer, or latter, of the two text inputs, i.e. the right should
	 * chronologically succeed the left.
	 * <p>
	 * Another term used for the right-hand side of a diff is the "destination".
	 * <p>
	 * Setting the text on either left or right side will cause this Differ to
	 * automatically recompute the differences upon the call of this method.
	 * 
	 * @param text
	 *            the text to set as the right-hand side destination of the
	 *            comparison
	 */
	public void setRightText(String text);

	/**
	 * This method provides an option to set both left and right-side text
	 * inputs at once. The text on the left should always be the older, or
	 * former, of the two text inputs, while the text on the right should always
	 * be the newer, or latter, of the two text inputs. In other words, the left
	 * should chronologically precede the right, and similarly the right should
	 * chronologically succeed the left.
	 * <p>
	 * Whenever this method is called to set the texts, this Differ will
	 * automatically recompute the differences between the left and right sides
	 * of the difference, and store the results in a property accessible via the
	 * {@link #getAllDifferences()} method.
	 * 
	 * @param leftText
	 *            the oldest of the two texts being compared
	 * @param rightText
	 *            the newest or more recent of the two texts being compared
	 */
	public void setTexts(String leftText, String rightText);

	/**
	 * Returns the left-side text input. The text on the left is always
	 * considered the older, or former, of the two text inputs, i.e. the left
	 * always chronologically precedes the right.
	 * <p>
	 * Differences between the left and right texts are interpreted as changes,
	 * revisions or modifications from left to right. In other words anything
	 * existing in the left-side text but not the right-side is considered
	 * deleted or removed, whilst anything existing on the right but not on the
	 * left has been added or inserted.
	 * <p>
	 * Another term used for the left-hand side of a diff is the "source".
	 * 
	 * @return a String containing the text that has been input on the left-side
	 *         of the diff (the oldest of the two texts)
	 */
	public String getLeftText();

	/**
	 * Returns the right-side text input. The text on the right is always
	 * considered the newer, or latter, of the two text inputs, i.e. the right
	 * always chronologically succeeds the left.
	 * <p>
	 * Differences between the left and right texts are interpreted as changes,
	 * revisions or modifications from left to right. In other words anything
	 * existing in the left-side text but not the right-side is considered
	 * deleted or removed, whilst anything existing on the right but not on the
	 * left has been added or inserted.
	 * <p>
	 * Another term used for the right-hand side of a diff is the "destination".
	 * 
	 * @return a String containing the text that has been input on the
	 *         right-side of the diff (the newest or more recent of the two
	 *         texts)
	 */
	public String getRightText();

	/**
	 * @return a list of deletions gathered from the given source text.
	 */
	public List<String> getDeletions();

	/**
	 * @return a list of insertions gathered from the given destination text.
	 */
	public List<String> getInsertions();

	/**
	 * @return a list of all of the known modifications gathered from the
	 *         differences between the two texts under comparison.
	 */
	public List<String> getAllDifferences();
}
